CHAIN Statement
 ----------------------------------------------------------------------------


 Action

 Transfers control from the current program to another program.


 Syntax

  CHAIN  filespec$


 Remarks

 The argument  filespec$ is a string expression that represents the program
 to which control is passed. It may include a path. (With DOS 2.1 or earlier
 versions, you cannot use  CHAIN unless  filespec$ provides a complete path,
 including drive. Also under DOS 2.1, if the run-time module is in the root
 directory, the root directory must be listed in the PATH environment
 variable.) Programs running within the QBX environment assume a .BAS
 extension (if no extension is given) and cannot chain to executable files
 (files with a .COM or .EXE extension). Programs running outside the BASIC
 environment assume a .EXE extension and cannot chain to BASIC source files
 (files with a .BAS extension).

 You can pass variables between programs using the  COMMON statement to set
 up a blank common block. For more information on passing variables, see the
 entry for the  COMMON statement.

 When you compile a program outside the QBX environment, the BCL70efr.LIB
 object-module library does not support  COMMON. There are two ways to use
 COMMON with chained programs outside the environment.

   -   Use the default (BRT70EFR.EXE for DOS and OS-2 real mode; BRT70EFR.DLL
       for OS-2 protected mode) by compiling the programs using the option in
       the Make EXE dialog box called "EXE Requiring BRT Module."

   -   Use BRT70EFR.LIB by compiling from the command line without the -O
       option. For more information, see Appendix C, "Command-Line Tools
       Quick Reference."


 Note

 When programs use BRT70EFR.EXE or BRT70EFR.DLL, files are left open during
 chaining unless they are explicitly closed with a  CLOSE statement. The
 filenames BCL70efr.LIB, BRT70EFR.EXE, and BRT70EFR.DLL assume that you
 selected these compiler options when you installed BASIC. emulator
 floating-point math, far strings, and real mode. If you used different
 options, see Chapter 17, "About Linking and Libraries" in the  Programmer's
 Guide for information about other compiler options.


  CHAIN is similar to  RUN. The main differences are that  RUN closes all
 open files and does not support data blocks declared with  COMMON.


 BASICA

 BASICA assumes the extension .BAS. The current version of BASIC assumes an
 extension of either .BAS or .EXE, depending on whether the program is run
 within the QBX environment or compiled and run outside the environment. If
 you omit the file extension,  CHAIN works the same in BASICA and in the
 current version of BASIC.

 The current version of BASIC does not support the all, merge, or delete
 option available in BASICA, nor does it allow you to specify a line number.

 Without the line-number option, execution always starts at the beginning of
 the chained-to program. Thus, a chained-to program that chains back to a
 carelessly written chaining program can cause an endless loop.


 See Also

  CALL (BASIC), Common,  RUN


 Example

 In the following example, the  COMMON statement is used to pass variables
 between two chained programs. The first program reads in a series of numeric
 values, stores the values in an array, then uses the  CHAIN statement to
 load and run the other program. The second program finds and prints the
 average of the values. The first two statements initialize the variables
 that are passed to PROG2.

 DIM values(1 TO 50)
 COMMON values(), NumValues%

 ' PROG2 creation section.
 ' The following few lines of code create the second program on the
 ' disk so that it can load and run with the CHAIN statement. It uses
 ' PRINT # statements to put the proper BASIC statements in a file.
 OPEN "PROG2.BAS" FOR OUTPUT AS #1
 PRINT #1, "' PROG2 for the CHAIN and COMMON statements example."
 PRINT #1, "DIM X(1 TO 50)"
 PRINT #1, "COMMON X(), N%"
 PRINT #1, "PRINT"
 PRINT #1, "IF N% > 0 THEN"
 PRINT #1, "   Sum% = 0"
 PRINT #1, "   FOR I% = 1 TO N%"
 PRINT #1, "      Sum% = Sum% + X(I%)"
 PRINT #1, "   NEXT I%"
 PRINT #1, "   PRINT "; CHR$(34); "The average of the values is";
 PRINT #1, CHR$(34); "; Sum% - N%"
 PRINT #1, "END IF"
 PRINT #1, "END"
 CLOSE #1
 ' End of PROG2 creation section.

 CLS
 PRINT "Enter values one per line. Type 'END' to quit."
 NumValues% = 0
 DO
    INPUT "-> ", N$
    IF I% >= 50 OR UCASE$(N$) = "END" THEN EXIT DO
    NumValues% = NumValues% + 1
    values(NumValues%) = VAL(N$)
 LOOP
 PRINT "Press any key to continue... "
 DO WHILE INKEY$ = ""
 LOOP
 CHAIN "PROG2.BAS"
 END